Skip to content

feat(harness-state): persist content-addressed harness state lineage - #78

Merged
Pepps233 merged 6 commits into
mainfrom
feat/persist-harness-state-lineage
Aug 17, 2026
Merged

Pepps233 merged 6 commits into
mainfrom
feat/persist-harness-state-lineage

Conversation

@Issacboy123

@Issacboy123 Issacboy123 commented Aug 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Diffex needs a stable, verifiable representation for evolvable harness memory before consumers can store revisions or reason about their lineage. This PR adds a private harness-state package that persists evolving memory as a portable directory bundle, identifies it via the packaged harness content's exact bytes (only EVOLVE.md for now) with a SHA-256 content hash, and records the predecessor hash used to derive each state. EVOLVE.md contains notes collected throughout the evolution process to improve Diffex's behavior. The packaged harness state intentionally remains separate from actual codebase changes.

Reasoning

Keeping the schema and persistence contract in a dedicated private package gives future consumers one runtime-validated ownership boundary without coupling storage to the coding agent. Hashing the exact memory bytes makes identity sensitive to all meaningful serialized content, including line endings and trailing whitespace. For now, the harness state is represented by the hash of its evolving memory notes. Names and more precise details can be included in the harness metadata in manifest.json later. Recording one base hash provides the minimum lineage primitive needed by later workflows without making this package responsible for resolving predecessors, validating graphs, or managing evolution.

A root state uses its own content hash as its base, so manifests remain structurally uniform without a nullable sentinel. The strict two-file layout keeps bundles inspectable and portable, while sibling staging and a final rename avoid exposing partially written destinations during normal saves. This structure is also scalable: when additional harness components can evolve, they can be represented in metadata or other files. The package deliberately does not provide cross-process coordination or durability guarantees beyond that staging boundary.

Changes

  • Added the private @diffexai/diffex-harness-state ESM workspace package with strict TypeBox state, manifest, and bundle schemas plus inferred readonly types.
  • Defined harness state with a memory field containing evolving notes from EVOLVE.md.
  • Defined manifests with a SHA-256 contentHash for the exact EVOLVE.md bytes and a required base hash identifying the predecessor.
  • Added bundle loading that enforces the exact two-file layout, direct regular files, fatal BOM-free UTF-8, strict manifest validation, content-hash verification, and verbatim memory preservation.
  • Added non-overwriting bundle saves with optional predecessor selection, self-based root manifests, canonical manifest serialization, sibling staging, a second destination check, final rename, and best-effort staging cleanup.
  • Returned the validated { state, manifest } bundle from both load and save operations so callers receive the persisted identity and lineage metadata.
  • Kept default-harness selection, predecessor resolution, graph validation, and coding-agent runtime integration outside the package contract.
  • Added package documentation and root workspace, build, offline-build, type-check path, and lockfile integration while keeping the package private.
  • Added focused coverage for schemas, lineage metadata, root semantics, content integrity, exact round trips, invalid encodings and manifests, filesystem layouts, overwrite refusal, cleanup, and partial-destination prevention.

Testing

  • node ../../node_modules/vitest/dist/cli.js --run test/harness-state.test.ts
  • npm run check

@Issacboy123 Issacboy123 added the enhancement New feature or request label Aug 16, 2026
@Issacboy123 Issacboy123 self-assigned this Aug 16, 2026
@Issacboy123
Issacboy123 requested a review from Pepps233 August 16, 2026 12:27
@Pepps233
Pepps233 marked this pull request as ready for review August 16, 2026 16:33
@Pepps233

Pepps233 commented Aug 16, 2026 •

Copy link
Copy Markdown
Contributor

9044109: rename from system prompt evolution → evolution memory notes

EVOLVE.md is not a file for system prompts; instead, it contains notes generated by the evolution process

For more context:

System prompts describe SYSTEM.md → this should be immutable because it is carefully tuned by us

Another layer of system prompts describe AGENTS.md/CLAUDE.md → this is handled by the user as user instructions

@Pepps233
Pepps233 merged commit ae744e8 into main Aug 17, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants